Fetch Details from Phone Number API

Objective

The Fetch Details from Phone Number API retrieves basic details associated with a user's phone number.

Input	Output
The user's Nigerian phone number	The first name, last name, gender and date of birth of the user

API Endpoint

getNameFromPhone

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Input

The following table provides the complete information on the parameter used in the request body for the API calls.

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
phoneNumber	The user's Nigerian phone number, starting with a 0.	Mandatory	The length of the phone number should be 11 digits	Not Applicable

Sample Request

The following code shows a standard cURL request for the API.

curl --location --request POST 'https://zaf.thomas.hyperverge.co/v1/getNameFromPhone' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "phoneNumber": "<Enter_the_Phone_Number>"
}'

Success Response Sample

{
  "statusCode": "200",
  "status": "success",
  "result": {
    "data": {
      "surname": "<Surname>",
      "firstName": "<First_Name>",
      "middlename": "<Middle_Name>",
      "gender": "<Gender>",
      "dateOfBirth": "<Date_Of_Birth_in_YYYY-MM-DD_Format>"
    }
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Success Response Details

Parameter	Type	Description
status	string	A status code that represents the result of the request
surname	string	The user's last name
firstName	string	The user's first name
middlename	string	The user's middle name
gender	string	The user's gender
dateOfBirth	string	The user's date of birth in the format YYYY-MM-DD

Failure Response Sample

The following is a sample response when no records of the entered phone number are found.

{
    "status": "failure",
    "statusCode": 404,
    "error": "Phone number not found",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Response Samples

Invalid Phone Number

{
    "status": "failure",
    "statusCode": 400,
    "error": "Invalid phone number supplied",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Input Validation Error

{
    "message": "Input Validation Error: does not meet minimum length of 11",
    "statusCode": 400,
    "status": "failure"
}

Missing/Invalid credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Internal Server Error

{
    "message": "Internal Server Error",
    "statusCode": 500,
    "status": "failure" 
}

Response Time Out

{
          "status": "failure",
          "statusCode": 503,
          "error": "Our data source has returned a timeout response, please retry the request.",
          "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Failure and Error Response Details

A failure or error response from the module contains a failure status, with a relavant status code and error message. The following table lists all error responses.

Status Code	Error Message	Error Description
400	Invalid phone number supplied	The provided Phone number is invalid
400	Input Validation Error: does not meet minimum length of 11	The provided number does not meet the minimum length of 11
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
403	Access Denied	Please contact the HyperVerge team for resolution
404	Phone number not found	The provided phone number does not match any identity at this point
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution
503	Our data source has returned a timeout response, please retry the request	The request to the data source timed out, please check your connection and try again